Release 10.1A: OpenEdge Development:
Progress 4GL Handbook

Subscribing to an event

Since a procedure has to subscribe to an event before anything happens when another procedure publishes it, you’ll look at the SUBSCRIBE statement first. Here is its syntax:

SUBSCRIBE [ PROCEDURE subscriber-handle ]   [ TO ] event-name-expr   { IN publisher-handle | ANYWHERE }   [ RUN-PROCEDURE local-internal-procedure ]   [ NO-ERROR ]

By default, a SUBSCRIBE statement registers the request on behalf of the external procedure that contains the SUBSCRIBE statement. The value of the procedure handle is the built-in Progress handle THIS-PROCEDURE. For the subscriber to receive the event, it must be running at the time the event occurs, so normally this means that you should only include a SUBSCRIBE statement in a procedure that is run persistent.

You can, however, create a service procedure that subscribes other procedures to events. In that case, you can include the PROCEDURE subscriber-handle phrase and the SUBSCRIBE is done on behalf of that other procedure handle.

The event-name-expr is a string expression holding the name of the event to publish. This is a standard Progress name of the same type as an internal procedure name. The default action when the event is published is to run an internal procedure in the subscriber with the same name as the event.

When you subscribe to an event, you can either subscribe to it in a specific running procedure handle that is available, or you can use the ANYWHERE keyword to indicate that you want to be notified when this event occurs anywhere in your session. If you specify the IN publisher-handle phrase, then the publisher must be a procedure that is already running and that remains running until it publishes the event. There is no way to subscribe to events that are published by procedures in other OpenEdge sessions.

One common practice is to subscribe to events that are published by the procedure that started the subscriber. The handle of that procedure is available in the SOURCE-PROCEDURE handle. An example in the "PUBLISH/SUBSCRIBE example" section shows you how this works.

A procedure can also subscribe to events in the SESSION handle. Other procedures can then publish events from the SESSION handle, thus using it as a kind of central coordinating point for events.

If the name of the internal procedure you want to run in response to the event must be different from the event name itself, then you include the RUN-PROCEDURE local-internal-procedure phrase in the SUBSCRIBE statement. You must implement the internal procedure in the subscriber (or one of its super procedures, if any).

If it is possible that the subscriber-handle or publisher-handle might not be valid at the time the statement is executed, you can include the NO-ERROR phrase to suppress any error messages that would result from this. In this case, the SUBSCRIBE has no effect, and the ERROR-STATUS handle holds a status and message describing the error.